From: Emmanuele Bassi <ebassi@gnome.org>
Date: Sun, 26 Mar 2023 14:59:14 +0000 (+0100)
Subject: docs: Try to steer people away from gdk_pixbuf_get_from_window()
X-Git-Tag: archive/raspbian/3.24.39-1+rpi1~1^2~65^2^2~25^2
X-Git-Url: https://dgit.raspbian.org/%22http://www.example.com/cgi/%22/%22http:/www.example.com/cgi/%22?a=commitdiff_plain;h=bda80c4e41ec7d7d9a8fc89371757c8967ab4d95;p=gtk%2B3.0.git

docs: Try to steer people away from gdk_pixbuf_get_from_window()

It's a bad function, and people should feel bad about using it.
---

diff --git a/gdk/gdkpixbuf-drawable.c b/gdk/gdkpixbuf-drawable.c
index e6fda26880..f3ce3d948a 100644
--- a/gdk/gdkpixbuf-drawable.c
+++ b/gdk/gdkpixbuf-drawable.c
@@ -51,9 +51,11 @@
  * @height: Height in pixels of region to get
  *
  * Transfers image data from a #GdkWindow and converts it to an RGB(A)
- * representation inside a #GdkPixbuf. In other words, copies
- * image data from a server-side drawable to a client-side RGB(A) buffer.
- * This allows you to efficiently read individual pixels on the client side.
+ * representation inside a #GdkPixbuf.
+ *
+ * In other words, copies image data from a server-side drawable to a
+ * client-side RGB(A) buffer. This allows you to efficiently read
+ * individual pixels on the client side.
  *
  * This function will create an RGB pixbuf with 8 bits per channel with
  * the size specified by the @width and @height arguments scaled by the
@@ -62,7 +64,8 @@
  *
  * If the window is off the screen, then there is no image data in the
  * obscured/offscreen regions to be placed in the pixbuf. The contents of
- * portions of the pixbuf corresponding to the offscreen region are undefined.
+ * portions of the pixbuf corresponding to the offscreen region are
+ * undefined.
  *
  * If the window you’re obtaining data from is partially obscured by
  * other windows, then the contents of the pixbuf areas corresponding
@@ -74,11 +77,13 @@
  * If memory can’t be allocated for the return value, %NULL will be returned
  * instead.
  *
- * (In short, there are several ways this function can fail, and if it fails
- *  it returns %NULL; so check the return value.)
+ * In short, there are several ways this function can fail, and if it fails
+ * it returns %NULL; so check the return value.
+ *
+ * You should rarely, if ever, need to call this function.
  *
  * Returns: (nullable) (transfer full): A newly-created pixbuf with a
- *     reference count of 1, or %NULL on error
+ *   reference count of 1, or %NULL on error
  */
 GdkPixbuf *
 gdk_pixbuf_get_from_window (GdkWindow *src,